Nómina de pago
Nómina de Pago — Visión General
La API de Nómina de Pago de BTG Empresas permite que su empresa gestione pagos masivos y el registro de colaboradores de forma centralizada, segura y rastreable. Esta documentación presenta los principales flujos disponibles y cómo utilizarlos en el día a día de su operación.
Flujo de Pagos
El flujo de pagos se organiza en torno al concepto de lote: una agrupación de pagos enviados juntos para procesamiento. Esto permite que su equipo financiero tenga control granular sobre cada remesa, con rastreabilidad completa de estados e historial de transacciones.
Crear Lote de Pago
El punto de entrada del flujo es el envío de un lote. En esta etapa, usted agrupa los pagos que deben procesarse en una misma remesa. La API soporta una amplia variedad de modalidades, como salario, adelanto, vacaciones, aguinaldo, indemnización, PLR, pro labore, beca de pasantía, beneficio, reembolso, comisión, dividendos y otras.
Al enviar el lote, usted define para cada línea el colaborador destinatario, el monto líquido, los datos bancarios de crédito y la fecha programada para la ejecución. El envío se procesa de forma asíncrona: la API responde de inmediato con el identificador del lote y el procesamiento ocurre en segundo plano.
Listado de Pagos
Todos los lotes enviados quedan disponibles para consulta. El listado permite que su equipo dé seguimiento al estado de cada remesa — identificando lotes enviados, en aprobación, liquidados, con falla o cancelados — y aplique filtros por período, estado, referencia u otros criterios relevantes para su contexto.
Atención: el listado aplica un filtro implícito por ventana de tiempo. Los pagos fuera de la ventana predeterminada pueden no aparecer incluso después de la liquidación. Utilice los filtros startDate y endDate para ampliar el período de búsqueda cuando sea necesario.
Detalles del Lote de Pago
Para cada lote, es posible acceder a una vista detallada con todas las líneas de pago que lo componen. Esta consulta muestra el estado individual de cada transacción, los montos involucrados, contadores de liquidaciones y fallas, y cualquier información de retorno del procesamiento bancario — como confirmaciones o errores por línea.
Los estados finales de un lote son settled (liquidado), failed (falló) y cancelled (cancelado). Use esta vista para auditar remesas específicas, identificar divergencias y obtener la visión consolidada de la operación.
Cancelar Lote de Pago
Es posible cancelar un lote que ya fue enviado, siempre que aún esté en los estados submitted (enviado) o pending_approval (esperando aprobación). La cancelación interrumpe el procesamiento del lote por completo.
Esta operación es irreversible: una vez cancelado, el lote no puede reactivarse. Si necesita reprocesar los pagos, deberá crear un nuevo lote.
Flujo de Colaboradores
La gestión de colaboradores es lo que viabiliza el flujo de pagos: cada destinatario de un lote debe estar registrado, con cuenta bancaria válida y estado activo en la plataforma. La API ofrece endpoints para cubrir todo el ciclo de vida de un colaborador — desde el onboarding hasta la baja y la reactivación.
Solicitud de Apertura de Cuenta
Para que un colaborador pueda recibir pagos vía nómina, es necesario registrarlo y solicitar la apertura de una cuenta digital BTG Empresas a su nombre. La solicitud se realiza con los datos de registro del colaborador — como CPF, nombre completo, fecha de admisión, salario bruto mensual, e-mail, teléfono, dirección y documento de identidad con su respectivo emisor — y desencadena el proceso de análisis y creación de la cuenta.
El envío es asíncrono: la API responde 202 Accepted de inmediato, y el procesamiento ocurre en segundo plano. El resultado puede seguirse consultando los detalles del colaborador o el estado de su cuenta bancaria.
Listado de Colaboradores
El listado presenta todos los colaboradores vinculados a su empresa, con sus respectivos estados. A partir de esta vista, es posible identificar colaboradores con cuenta activa (active), onboarding en curso (pending), cuenta suspendida (suspended) y colaboradores dados de baja (inactive).
El listado soporta filtros por estado, nombre, CPF, tipo de cuenta, portabilidad y tipo de contrato, además de paginación por cursor, siendo adecuado tanto para uso en interfaces administrativas como para integraciones automatizadas con sistemas de RR. HH.
Seguimiento de la Apertura de Cuenta
Por tratarse de un proceso asíncrono, la apertura de cuenta puede seguirse de dos formas: consultando el estado del colaborador en el listado general (donde aparecerá como pending mientras el onboarding esté en curso) o consultando específicamente los datos de la cuenta bancaria del colaborador, que devuelve el estado actual del onboarding, la fecha de conclusión y eventuales errores.
Se recomienda implementar un mecanismo de polling en estas consultas para monitorear la evolución del estado sin necesidad de verificaciones manuales recurrentes.
Detalles del Colaborador
La consulta de detalles devuelve el perfil completo de un colaborador registrado: sus datos personales, estado actual, tipo de contrato, información de portabilidad, fechas de admisión y baja, estado de suspensión y la información de cuenta bancaria vinculada.
Use esta consulta para verificar la elegibilidad de un colaborador para recibir pagos antes de incluirlo en un lote, o para soporte y auditoría de casos específicos.
Inactivar y Activar Colaborador
Al dar de baja a un colaborador, es posible registrar el fin del vínculo laboral en la plataforma. Esta operación está disponible para colaboradores con estado active y los mueve al estado inactive, impidiendo que sean incluidos en nuevos lotes de pago. La baja acepta fecha de rescisión y motivo.
La reactivación también está disponible: si el colaborador regresa a la empresa, puede ser reactivado — siempre que esté en el estado inactive — volviendo al estado active y siendo nuevamente elegible para recibir pagos vía nómina.